<html>
<!-- $LastChangedDate: 2009-11-22 22:39:11 -0500 (Sun, 22 Nov 2009) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - FX Module</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - FX Module</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#FX container'>FX container</a></li>
  <li><a href='#ParticleSystem'>ParticleSystem</a></li>
      <ul>
        <li><a href='#SmallParticles'>SmallParticles</a></li>
        <li><a href='#BigParticles'>BigParticles</a></li>
        <li><a href='#ParticleSystemFX'>ParticleSystemFX</a></li>
        <li><a href='#Implementing and Using Particle Systems'>Implementing and Using Particle Systems</a></li>
      </ul>
  <li><a href='#Sprite'>Sprite</a></li>
  <li><a href='#Texture'>Texture</a></li>
  <li><a href='#ImageCache'>ImageCache</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2008/08]</p>
<p>
The fx module (special-effects) provides graphical objects such as Sprite, Texture, ParticleSystem.
The FX class contains and makes special-effects (explosions, smoke, etc).
FX::Reset() stops special-effects.
</p>
<p>
Facade classes are used for many graphics primitives.
These lessen dependence on a graphics system, can overcome its limitations,
and are more convenient to use.
For example, the Sprite class hides an osg::AutoTransform and automatically constructs its nodes.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='FX'></a>
<a name='FX container'></a>
<a name='FX class'></a>
<h2>FX container</h2>
<p><!--date-->[2008/11]</p>
<p>
The FX class is a container of special-effects objects.
Reasons for the FX container are:
some FX objects cannot be attached to the scene-graph,
a container simplifies destroying all FX objects when program is reset,
and particles may out-live the Object that originally spawned them
(missile trail can persist after the missile).
</p>
<p>
Special-effect objects, such as ParticleSystem, schedule their deletion with FX,
thus turning into zombies, which FX::Tick() destroys.
</p>
<p>
Source files with the prefix <i>fx_</i> are private implementations of the FX class.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='ParticleSystem'></a>
<a name='Particle System'></a>
<a name='Particle'></a>
<h2>Particle System</h2>
<p><!--date-->[2008/11]</p>
<pre>
ParticleSystem<img src='images/arrowGreen.gif' hspace='8'>BigParticleSystem<img src='images/arrowGreen.gif' hspace='8'>ExplosionParticleSystem
              <img src='images/arrowGreen.gif' hspace='8'>SmallParticleSystem<img src='images/arrowGreen.gif' hspace='8'>TrailParticleSystem
</pre>
<p>
The two main classes are for <i>small</i> and <i>big</i> particles.
</p>

<a name='SmallParticles'></a>
<h2>SmallParticles</h2>
<p><!--date-->[2008/11]</p>
<p>
SmallParticles are lightweight and render quickly, but have limitations.
</p>
<p>
The update mechanism is SmallParticleFunctor::operator()(const SmallParticle&amp;).
ParticleSystem passes every SmallParticle to the functor.
<code>SmallParticle</code> is a opaque POD struct that doesn't persist.
After calling, modifications made by the functor to a SmallParticle struct
will be applied by ParticleSystem to underlying graphical objects (vertex array element).
</p>
<h3>Implementation</h3>
<p>
SmallParticles are implemented as OpenGL <i>point sprites</i>.
Hardware limits point size (64 pixels max, typically).
</p>

<a name='BigParticles'></a>
<h2>BigParticles</h2>
<p><!--date-->[2008/11]</p>
<p>
BigParticle is derived from the <a href='#Sprite'>Sprite class</a>.
BigParticle::Tick() is a virtual method, called by ParticleSystem,
for doing animation such as altering color, alpha, position, etc.
</p>
<p>
Custom particle systems can be made by making derivatives
of both ParticleSystem and Particle then overriding both of their Tick() methods.
<br>DerivedParticleSystem::Tick() would add more particles.
<br>DerivedParticle::Tick() would animate an individual particle.
</p>

<a name='Implementing and Using Particle Systems'></a>
<h2>Implementing and Using Particle Systems</h2>
<p><!--date-->[2008/11]</p>
<p>
The ParticleSystem classes are private implementations of the FX class.
FX shall provide interface methods such as FX::MakeExplosion().
Behind-the-scenes, FX:MakeExplosion() calls "new ExplosionParticleSystem"
and contains it.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Sprite'></a>
<h2>Sprite</h2>
<p><!--date-->[2008/08]</p>
<p>
A sprite is 2D textured quad in 3D space aligned to the viewplane.
The Sprite class hides an osg::AutoTransform and automatically constructs its nodes.
</p>
<p>
See
<a href='http://www.devili.iki.fi/Computers/Commodore/C64/Programmers_Reference/front_cover.html'>Commodore 64 Programmer's Reference Guide</a>.
</p>
<p>
<img src='images/sprite1.png'>
<img src='images/sprite2.png'>
<img src='images/sprite3.png'>
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Texture'></a>
<h2>Texture</h2>
<p><!--date-->[2008/02]</p>
<p>
The Texture class abstracts a texture image file and/or a texture object.
Texture ctor uses ImageCache to cache texture images.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='ImageCache'></a>
<h2>ImageCache</h2>
<p><!--date-->[2008/02]</p>
<p>
Caches 2D image files.  Used by <a href='#Texture'>Texture class</a>.
</p>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Sun Nov 22 21:22:58 CST 2009
<!-- hhmts end -->
</font>
</p>

</body>
</html>
